6  Running NPAG

First, you must always load the Pmetrics library in your R script or Quarto document.

library(Pmetrics)

6.0.1 Working directory

Next, R and Pmetrics need to know which directory to work in. This is the directory where R expects to find files and where it will save output files. There are two ways to do this.

6.0.1.1 Global working directory change

You can set your working directory with the setwd function.

setwd("/path/to/your/project/directory") # Mac and Linux users
setwd("C:/path/to/your/project/directory") # Windows users

Windows users: Make sure that you separate directories with a forward slash “/” or double backslashes “\”. Unfortunately, Windows is the only OS that uses backslashes ““, so R conforms to Unix/Linux style with the forward slash. If you copy the example below, make sure to change the path to one that exists on your computer.

6.0.1.2 Local path specification

You can also specify the path in a variable and use it in Pmetrics functions without changing the working directory.

wd <- "/path/to/your/project/directory" # Mac and Linux users
wd <- "C:/path/to/your/project/directory" # Windows users
dat <- PM_data$new(data = file.path(wd, "data", "mydata.csv"))

💡 The file.path function creates file paths that are compatible with your operating system.

6.0.2 Workflow

The typical workflow for using Pmetrics is as follows:

1. Create a PM_data object.
2. Create a PM_model object.
3. Fit the model to the data with the $fit() method of the model object. This returns a PM_result object, which is also saved to the hard drive and can be loaded later with the PM_load function.
4. Examine the results with PM_result methods and functions and revise as needed to improve the model fit. This chiefly means using the $update() method to change the model or manually editing it.

flowchart LR

subgraph RSession[" "]
  direction TB
  DATA["PM_data"]
  MODEL["PM_model"]
  RESULT["PM_result"]
end

DISK[("Hard Drive")]

DATA --> MODEL
MODEL -- "$fit()" --> RESULT
RESULT -- "$update()" --> MODEL
DISK -- "PM_load()" --> RESULT
RESULT --> DISK

classDef blue fill:#2f6db6,stroke:#184a8b,color:#fff;
classDef orange fill:#c7662b,stroke:#8a3f18,color:#fff;
classDef disk fill:#d2d3d7,stroke:#7f8084,color:#000;

class DATA,MODEL blue;
class RESULT orange;
class DISK disk;

style RSession fill:#e9f0ff,stroke:#9ab0d6,stroke-width:1px,rx:2,ry:2

6.0.3 Data objects

Pmetrics always needs data and a model to run, so let’s create a new data object.

exData <- PM_data$new(data = "Data/src/ex.csv")

── DATA STANDARDIZATION ────────────────────────────────────────────────────────

EVID inferred as 0 for observations, 1 for doses.
 All doses assumed to be oral (DUR = 0).
 ADDL set to missing for all records.
 II set to missing for all records.
 All doses assumed to be INPUT = 1.
 All observations assumed to be OUTEQ = 1.
 All observations assumed to be uncensored.
 One or more error coefficients not specified. Error in model object will be used.

── DATA VALIDATION ─────────────────────────────────────────────────────────────

No data errors found.

Pmetrics standardizes the data, checks for errors, and provides an error and attempted fix report fo any found.

You can look at a .csv data file directly by opening it in a spreadsheet program like Excel, or a text editor.

exData is an R6 object, which means that contains both data and methods to process that data.

exData # prints the object, usually to the terminal, but in this case to a rendered "lite" spreadsheet
exData$data # contains your original data
exData$standard_data # contains the standardized and validated data
exData$summary() # prints the summary of the data to the terminal

Most Pmetrics objects are R6 objects, so you can use the $ operator to access their data and methods. Many of them have a summary() method that prints a summary of the object to the console and a plot() method that creates a plot of the object. See PM_data for more information on the PM_data class and its methods.

Note: We recognize that many users are familiar with the “S3 framework” in R, which uses functions like summary(object) and plot(object). To comply with better programming standards, Pmetrics uses the R6 framework. However, we have provided S3 methods for most functions, so you can use summary(object) and plot(object) if you prefer.

# S3 method to summarize data
summary(exData)

PM_data has a plot() method that creates a plot of the data. See plot.PM_data for more information.

exData$plot() 

6.0.4 Model objects

You can specify a model by reading a file or directly as a list object in R. We’ll do both.

The following code creates the same model as in /src/model.txt file. See further model details on creating models in R compared to text files. The advantage of creating them in R is that one does not need to copy model files into folders to provide necessary inputs.

mod1 <- PM_model$new(
  pri = list(
    Ka = ab(0.1, 0.9),
    Ke = ab(0.001, 0.1),
    V = ab(30, 120),
    lag1 = ab(0, 4)
  ),
  cov = list(
    wt = interp(),
    africa = interp("none"),
    age = interp(),
    gender = interp("none"),
    height = interp()
  ),
  eqn = function(){
    two_comp_bolus
  },
  lag = function(){
    lag[1] = lag1
  },
  out = function(){
  Y[1] = X[2]/V
  },
  err = list(
    proportional(5, c(0.02, 0.05, -0.0002, 0))
  )
)

ℹ Compiling model...

Using template path: /Users/mneely/Library/CloudStorage/OneDrive-CHILDRENSHOSPITALLOSANGELES/Documents/LAPK/Development/Pmetrics_rust/inst 

When you execute the above code in your own script or Quarto document, you will see a message indicating that the model has compiled.

mod1 # prints the model object

── Model summary ───────────────────────────────────────────────────────────────

── Primary Parameters 

Ka: [0.1, 0.9], ~N(0.5, 0.13)

Ke: [0.001, 0.1], ~N(0.05, 0.02)

V: [30, 120], ~N(75, 15)

lag1: [0, 4], ~N(2, 0.67)

── Covariates 

wt, africa (no interpolation), age, gender (no interpolation), and height

── Primary Equations 

two_comp_bolus

── Lag Time 

lag[1] = lag1

── Outputs 

Y[1] = X[2]/V

── Error Model 

Proportional, with initial value of 5 and coefficients 0.02, 0.05, -2e-04, and
0.

mod1$plot() 

We have another file “model.txt” that contains the old representation of the same model we coded above, let’s take a look at it.

system("cat Data/src/model.txt")

You can also open it in a text editor.

PM_model$new() also accepts the path to a model file to create the same model using the file.

mod1b <- PM_model$new("Data/src/model.txt")
mod1b # look at it

To copy a model use the $clone() method.

mod1b <- mod1$clone()

Simply using mod1b <- mod1 will cause mod1b to be changed if mod1 is changed, as R6 objects use reference semantics. For more details you can refer to Advanced R, Section 14.4.

6.0.5 Fit the model to the data

To keep everything tidy, we are working in a folder specifically to store the runs. We are specifying the path in the call to $fit() rather than globally changing the working directory.

run1 <- mod1$fit(data = exData, run = 1, overwrite = TRUE, path = "Data/Runs") 

The PM_model class has a $fit() method that fits the model to the data.

After the run is complete the results are returned to the assigned object, here ‘run1’. However, if you want to load the results later, you can use the PM_load() function. Runs will be sequentially numbered as /1, /2, /3,… in your working directory.

run1 <- PM_load(1, path = "Data/Runs") # load the results from run 1 if returning to this script later